﻿#region Copyright (c) Lokad 2009
// This code is released under the terms of the new BSD licence.
// URL: http://www.lokad.com/
#endregion

using System;
using System.IO;
using System.Xml.Linq;

namespace Lokad.Cloud
{
	/// <summary>Defines the interface for a custom formatter.</summary>
	public interface IBinaryFormatter
	{
		/// <summary>Serializes an object to a stream.</summary>
		/// <param name="destination">The destination stream.</param>
		/// <param name="instance">The object.</param>
		void Serialize(Stream destination, object instance);

		/// <summary>Deserializes an object from a stream.</summary>
		/// <typeparam name="T">The type of the object.</typeparam>
		/// <param name="source">The source stream.</param>
		/// <param name="type">The type of the object.</param>
		/// <returns>The deserialized object.</returns>
		object Deserialize(Stream source, Type type);
	}

	/// <summary>
	/// Optional extension for custom formatters supporting an
	/// intermediate xml representation for inspection and recovery.
	/// </summary>
	/// <remarks>
	/// This extension can be implemented even when the serializer
	/// is not xml based but in a format that can be transformed
	/// to xml easily in a robust way (i.e. more robust than
	/// deserializing to a full object). Note that formatters
	/// should be registered in IoC as IBinaryFormatter, not by
	/// this extension interface.
	/// </remarks>
	public interface IIntermediateBinaryFormatter : IBinaryFormatter
	{
		/// <summary>Unpack and transform an object from a stream to xml.</summary>
		XElement UnpackXml(Stream source);

		/// <summary>Transform and repack an object from xml to a stream.</summary>
		void RepackXml(Stream destination, XElement data);
	}
}
